home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / os2 / plnk081.zip / pilot-link.0.8.1 / Python / README < prev    next >
Encoding:
Text File  |  1997-08-03  |  5.6 KB  |  163 lines
  1.  
  2. As of 0.8.0: Any documentation included is dubious at best.
  3.  
  4.  
  5. New, as of 0.7.3: the module has been completely overhauled to support a
  6. more robust installation process ('make install' might just work!) and the
  7. actual interface has been substantially modified to automatically pack and
  8. unpack records.
  9.  
  10. Note that currently only packing/unpacking is implemented for Memos, ToDos,
  11. and two of the Mail preferences, but extending this is merely a SMOP.
  12.  
  13. I'll try and give a slight taste of how it now works. 
  14.  
  15.    socket = pdapilot.OpenPort('/dev/cua3') # Shorthand for open serial
  16.                                            # connection, returns an integer
  17.  
  18.    dlp = pdapilot.Accept(port) # Returns a new object when the connection succeeds
  19.    
  20.    db = dlp.Open('MemoDB')  # Open the database, return yet another object
  21.    
  22.    print db.Class      # Shows that pdapilot.Memo has been chosen.  You
  23.                        # could deactivate packing by switching to a more
  24.                        # primitive class: db.Class = pdapilot.RecordDatabase
  25.    
  26.    r = db.GetRecord(0) # Get the first record, returning an object
  27.                        # of pdapilot.Memo.Record class. r.raw is the record
  28.                        # contents, r.text contains the unpacked text, and
  29.                        # r.id, r.attr, & r.category contain the obvious.
  30.    
  31.    print r # Dump the record to show what it contains
  32.    
  33.    r.text = r.text + "Hello world!" # append text to record
  34.    
  35.    db.SetRecord(r) # Write record to database. Since it contains the
  36.                    # original ID number, this overwrites the original record
  37.                    # with this new one.
  38.  
  39.    r2 = db.NewRecord() # Construct a new blank record with appropriate
  40.                        # attributes for the Memo database.
  41.                        # This record could also have been constructed via
  42.                        # pdapilot.Memo.Record()
  43.  
  44.    r2.text = 'Hello again!'
  45.    
  46.    r2.id = 0 # Must set ID
  47.    
  48.    db.SetRecord(r2) # Append record (since ID is zero, a new ID will be assigned)
  49.    
  50.    r3 = pdapilot.Database.Record() # Construct new blank record that is not
  51.                                    #  specific to Memo
  52.    
  53.    r3.raw = "Foo\0" # Access the raw record. Actually, all of the "r"
  54.                     # objects have contained a raw attribute. Note that
  55.                     # changes to the raw attribute are not automatically
  56.                     # mirrored in the unpacked slots (and vice versa).
  57.                     # Changes to the raw data will not be respected when the
  58.                     # block is repacked.
  59.  
  60.    r4 = db.NewAppBlock() # Returns an empty pdapilot.Memo.AppBlock object
  61.    
  62.    print r4.categoryname # print out the categories
  63.    
  64.    print r4.pack() # Show what the packed record looks like (this incidentally updates r4.raw)
  65.    
  66. ---
  67.  
  68.  
  69. This is an experimental piece of code to interface Python to the pilot-link
  70. library. To use it, you will have to figure out how to link and install the
  71. .c file so that your Python installation can use it. The included Makefile
  72. will probably only work for ELF systems.
  73.  
  74. (Note that I have only tested this with Python 1.4, and have no particular
  75. expectation of it working with earlier or later versions.)
  76.  
  77. Usage notes:
  78.  
  79.     Start with 'importing pdapilot'.
  80.     
  81.     Look at test.py for examples of simple usage.
  82.     
  83. Documentation (such as it is):    
  84.     
  85.     pdapilot.OpenPort(device): Open a device, ready for Accept
  86.         
  87.         returns a file descriptor which may be used to access the given device
  88.         (serial port) with the Accept routine.
  89.         
  90.         This routine is built out of Socket, Bind, & Listen.
  91.  
  92.     pdapilot.Socket(domain,type,protocol): returns a new pilot socket.
  93.  
  94.     pdapilot.Bind(socket, address): binds a socket to the given address.
  95.  
  96.     pdapilot.Listen(socket, backup):
  97.     
  98.     pdapilot.Accept(socket): Waits for incoming Pilot connection
  99.     
  100.         returns a new pdapilot.dlp object if a connection succeeds.
  101.     
  102.     pdapilot.FileOpen(filename): Opens the named .prc or .pdb file
  103.     
  104.         returns a new pdapilot.file object if the file can be opened.
  105.     
  106.     pdapilot.FileCreate(filename, info): Creates the named .prc or .pdb file
  107.     
  108.         returns a new pdapilot.file object if the file can be created.
  109.         info must be a dictionary containing elements such as these:
  110.         
  111.             flags, miscflags, type, creator, version, index, modnum,
  112.             crdate, moddate, backupdate, name
  113.         
  114.         type and creator may each be an integer or a 4-character string.
  115.     
  116.     pdapilot.MemoUnpack(string): Unpacks a Memo record
  117.     
  118.         Treats string as a record from the MemoDB database and returns
  119.         the contents in a dictionary.
  120.  
  121.     pdapilot.MemoPack(dict): Packs a Memo record
  122.     
  123.         Packs the dictionary into a string suitable for insertion
  124.         in the MemoDB database.
  125.  
  126.     pdapilot.MemoUnpackAppBlock(string): Unpacks a Memo App block
  127.     
  128.         Treats string as the AppBlock from the MemoDB database and returns
  129.         the contents in a dictionary.
  130.  
  131.     pdapilot.MemoPackAppBlock(dict): Packs a Memo App block
  132.     
  133.         Packs the dictionary into a string suitable for putting
  134.         in the MemoDB database's AppBlock.
  135.  
  136.     pdapilot.TodoUnpack(string): Unpacks a Todo record
  137.  
  138.     pdapilot.TodoPack(dict): Packs a Todo record
  139.  
  140.     pdapilot.TodoUnpackAppBlock(string): Unpacks a Todo App block
  141.  
  142.     pdapilot.TodoPackAppBlock(dict): Packs a Todo App block
  143.     
  144. Methods of pdapilot.dlp:
  145.     
  146.     Close(status=0): Closes the Pilot connection
  147.     
  148.         If status is non-zero, convey that status to the Pilot.
  149.         Note that Close is automatic on destruction of a pdapilot.dlp
  150.         object.
  151.  
  152.     Open(name): Opens a database
  153.     
  154.         returns a new pdapilot.dlp.db object if successful, otherwise
  155.         throws pdapilot.error.
  156.  
  157.     Create(name,...): Creates a database
  158.     
  159.         returns a new pdapilot.dlp.db object if successful, otherwise
  160.         throws pdapilot.error.
  161.  
  162.     etc.
  163.